Skip to content

Docs: add any feature gaps#409

Merged
alexluckett merged 8 commits into
mainfrom
docs/gaps
May 19, 2026
Merged

Docs: add any feature gaps#409
alexluckett merged 8 commits into
mainfrom
docs/gaps

Conversation

@alexluckett
Copy link
Copy Markdown
Contributor

@alexluckett alexluckett commented May 19, 2026

Proposed change

Patches some gaps in documentation we have.

  • Add Conditions page documenting condition types, operators, composition, and multi-item logic
  • Add Form Definition Formats page (moved to Code-based Features) covering FileFormService file loading and the custom formsService interface
  • Add Session Cache page (moved to Code-based Features) covering named catbox cache and CacheService subclass setup
  • Add Form Definition Options page (top-level Feature) covering lists, sections, reference number display/prefix, user feedback, phase banner, and declaration
  • Add Lists documentation — structure, property reference, how to assign lists to components, and link to ListItemRef conditions
  • Add Template Extensions standalone page covering custom Nunjucks globals and filters
  • Restore Page Elements as a top-level Feature (was dropped from the Features nav on this branch)
  • Expand Getting Started guide with a fuller walkthrough
  • Expand Plugin Options with full option details and examples
  • Expand Request Lifecycle with detailed stage-by-stage breakdown
  • Expand Page Events and Page Templates documentation
  • Reduce Reference section to Request Lifecycle only — other content redistributed into Features

Jira ticket:

Type of change

  • Bug fix
  • New feature
  • Breaking change
  • Misc. (documentation, build updates, etc)

Checklist

  • You have executed this code locally and it performs as expected.
  • You have added tests to verify your code works.
  • You have added code comments and JSDoc, where appropriate.
  • There is no commented-out code.
  • You have added developer docs in README.md and docs/* (where appropriate, e.g. new features).
  • The tests are passing (npm run test).
  • The linting checks are passing (npm run lint).
  • The code has been formatted (npm run format).

@alexluckett
docs: fill gaps in plugin documentation
fc2f302 
- Add StatusPageController to generated page docs (metadata, fixture,
  preview with reference number panel)
- Add app-no-prose to all generated previews by default; add wrapperClass
  hook to page preview generator for future overrides
- Fix union type pipe escaping in generated configuration tables
- New hand-written pages: form-definition-options (sections, declaration,
  phaseBanner, showReferenceNumber, referenceNumberPrefix)
- Rewrite custom-services to document all three service interfaces with
  TypeScript signatures; add output.audience/version; clarify Defra Forms
  submission API scope
- Rewrite pre-populate-state with accurate mechanics (QuestionPageController,
  global HiddenField scan, GET param forwarding) and working examples
- Expand plugin-options cache section to cover CacheService instance path;
  collapse saveAndExit to a signpost
- Expose form-definition-options in docusaurus nav under Reference
- Add AGENTS.md with generated-vs-handwritten docs guidance and
  app-no-prose convention
@alexluckett
docs: extract template extensions and session cache into standalone p…
1b246e8 
…ages

- Move globals + filters out of plugin-options into features/code-based/template-extensions,
  with built-in filters table and LiquidJS cross-reference
- Move cache setup out of plugin-options into session-cache, clarifying
  named catbox cache (simple) vs CacheService subclass (full lifecycle override)
- Collapse both plugin-options sections to signposts
- Add template-extensions to code-based index
- Expose session-cache in Reference nav sidebar
@alexluckett
docs: reorganise reference section into features
fb5af5f 
Move form definition formats and session cache under features/code-based,
move form definition options under features, and restore page elements as
a top-level feature. Add lists documentation to form definition options.
Reference section now contains only the request lifecycle.
@alexluckett
test: update preview tests to expect app-no-prose class
7d03705
jbarnsley10
jbarnsley10 reviewed May 19, 2026
View reviewed changes
Comment thread docs/features/code-based/custom-services.md
jbarnsley10
jbarnsley10 reviewed May 19, 2026
View reviewed changes
Comment thread docs/features/code-based/form-definition-formats.md
jbarnsley10
jbarnsley10 reviewed May 19, 2026
View reviewed changes
Comment thread docs/features/form-definition-options.md
jbarnsley10
jbarnsley10 reviewed May 19, 2026
View reviewed changes
Comment thread docs/features/form-definition-options.md
### User feedback

`options.disableUserFeedback` — when `true`, the "What do you think of this service?" feedback link is suppressed on all pages, including the confirmation page. Defaults to `false`.

Copy link
Copy Markdown
Contributor

@jbarnsley10 jbarnsley10 May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to add that it reverts to a 'mailto', and where the mail link comes from?

Copy link
Copy Markdown
Contributor Author

@alexluckett alexluckett May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just did a bit of digging and it's a bit more complicated than i thought. i'll come back to this separately.

jbarnsley10
jbarnsley10 approved these changes May 19, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@jbarnsley10 jbarnsley10 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very thorough. A couple fo minor comments but approving anyway.

alexluckett and others added 4 commits May 19, 2026 16:43
@alexluckett
docs: add componentSecrets support and document PaymentField secrets
56e902e 
Adds a named componentSecrets feature to the doc generation script so
components can declare what per-form secrets they require. Generates a
standard "Required secrets" section with a getFormSecret blurb and a
secrets table. PaymentField is the first consumer.

Also clarifies in custom-services.md that getFormSecret is per-form
scoped, distinct from global plugin options such as ordnanceSurveyApiKey,
and safe to leave unimplemented when no secret-using components are present.
@alexluckett
fix: correct relative path in getFormSecret docs link
ae78583
@alexluckett
document relationship between gov pay and ref number
5a7e1d2
@alexluckett
Merge branch 'main' into docs/gaps
37a9aa7
@alexluckett alexluckett enabled auto-merge May 19, 2026 15:59
@sonarqubecloud
Copy link
Copy Markdown

sonarqubecloud Bot commented May 19, 2026

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@alexluckett alexluckett merged commit efe00ef into main May 19, 2026
23 checks passed
@alexluckett alexluckett deleted the docs/gaps branch May 19, 2026 16:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jbarnsley10 jbarnsley10 jbarnsley10 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@alexluckett @jbarnsley10